Skip Headers

Oracle® Transparent Gateway for DRDA Installation and User's Guide 10g Release 2 (10.2) for UNIX Part Number B16217-02 |
Home | Book List | Contents | Index | Master Index | Feedback

Previous | Next
| View PDF

# C DRDA-Specific Parameters

This appendix contains the DRDA-specific parameters that are defined in the Gateway Initialization File. The appendix contains the following sections:

- Modifying the Gateway Initialization File

- Setting Parameters in the Gateway Initialization File

- Syntax and Usage

- Gateway Initialization File Parameters

## Modifying the Gateway Initialization File

If you change any parameters in the Gateway Initialization File, then you must stop and restart the gateway in order for them to take effect. If you change certain parameters, then you must also rebind the DRDA package. Any parameters that affect the DRDA package have a note in their description that rebinding is required.

## Setting Parameters in the Gateway Initialization File

Parameters that are specific to the gateway are stored in the Gateway Initialization File, `initsid.ora`.

## Syntax and Usage

Parameters and their values are specified according to the syntax rules that are specified by Heterogeneous Services. The general form is:

    [set] [private] drda_parameter = drda_parameter_value

where:

`drda_parameter` is one of the DRDA parameters

`drda_parameter_value` is a character string with contents depending `drda_parameter.`

The `set` and `private` keywords are optional. If the `set` keyword is present, then the parameter and its value will be passed to the process environment. This might be necessary if parameters from the Startup Shell Script are moved into the Gateway Initialization File. If the `private` keyword is present, then the parameter and its value will not be uploaded to Oracle Database. In general, Oracle recommends that the `private` keyword unless the parameter contains sensitive information (a userID or password).

For further information on Heterogeneous Services and Initialization Parameters, refer to the section "Setting Initialization Parameters" in the Oracle Database Heterogeneous Connectivity Administrator's Guide.

## Gateway Initialization File Parameters

The following sections list gateway-specific initialization file parameters and their descriptions. In addition to these parameters, generic Heterogeneous Services initialization file parameters may be set. Refer to the Oracle Database Heterogeneous Connectivity Administrator's Guide for a list of additional parameters.

### DRDA_CACHE_TABLE_DESC

Default value: `TRUE`

Range of values: {`TRUE`|`FALSE`}

Syntax: `DRDA_CACHE_TABLE_DESC=``{TRUE|FALSE}`

`DRDA_CACHE_TABLE_DESC` directs the gateway to cache table descriptions once per transaction. This can reduce the number of table lookups requested by Oracle Database and can speed up the execution of SQL statements. You may wish to disable this option if you would be altering the structure of a remote table and if you would be examining it within the same transaction.

### DRDA_CAPABILITY

Default value: None

Range of values: Refer to "Native Semantics"

Syntax: `DRDA_CAPABILITY={``FUNCTION/{ON|OFF}``},...`

`DRDA_CAPABILITY` specifies which mapped functions of Oracle Database will be treated natively. In other words, no special pre processing or post processing will be done for these functions. They will be passed through to the DRDA Server unmodified.

### DRDA_CODEPAGE_MAP

Default value: `codepage.map`

Range of values: Any valid file path

Syntax: `DRDA_CODEPAGE_MAP=``codepage.map`

`DRDA_CODEPAGE_MAP` specifies the location of the codepage map. You may specify only the filename, which will be searched for within the `$ORACLE_HOME/tg4drda/admin` directory, or you may specify the full path name of the file.

### DRDA_COMM_BUFLEN

Default value: 32767

Range of values: 512 through 32767

Syntax: `DRDA_COMM_BUFLEN=``num`

`DRDA_COMM_BUFLEN` specifies the communications buffer length. This is a number indicating the size of the SNA send or receive buffer in bytes.

### DRDA_CONNECT_PARM (SNA format)

Default value: `DRDACON1`

Range of values: Any alphanumeric string 1 to 8 characters in length

Syntax: `RDA_CONNECT_PARM=``name`

`DRDA_CONNECT_PARM` specifies the Side Information name. Refer to Chapter 6, Chapter 6, Chapter 7, and Chapter 8 for details.

### DRDA_CONNECT_PARM (TCP/IP format)

Default value: `DRDACON1:446`

Range of values: Any alphanumeric string 1 to 255 characters in length

Syntax: `DRDA_CONNECT_PARM={``hostname|ip_address``}{``:port``}`

`DRDA_CONNECT_PARM` specifies the TCP/IP hostname or IP Address of the DRDA Server and, as an option, the Service Port number on which the DRDA Server is listening. For more information about the port number, refer to "Port Number".

### DRDA_CMSRC_CM_IMMEDIATE

Default value: `FALSE`

Range of values: {`TRUE` |`FALSE`}

Syntax: `DRDA_CMSRC_CM_IMMEDIATE={``TRUE|FALSE``}`

`DRDA_CMSRC_CM_IMMEDIATE` sets the SNA session allocation mode. A setting of `FALSE` causes the gateway to wait for a free session if no free sessions exist. A setting of `TRUE` causes the gateway to fail the allocation immediately if no free sessions exist.

### DRDA_DEFAULT_CCSID

Default value: None

Range of values: Any supported DRDA Server CCSID

Syntax: `DRDA_DEFAULT_CCSID=``ccsid`

`DRDA_DEFAULT_CCSID` specifies the default CCSID or character set codepage for character set conversions when the DRDA Server database indicates that a character string has a CCSID of 65535. DRDA Servers use CCSID 65535 for columns specified as `"FOR BIT DATA"`. In most cases, this parameter should not be specified, allowing CCSID 65535 to be treated as an Oracle RAW data type.

This parameter is for supporting databases (in particular, DB2/400) that use CCSID 65535 as the default for all tables created. Allowing CCSID 65535 to be treated as another CCSID can save such sites from having to modify every table.

Warning: Specifying any value for DRDA_DEFAULT_CCSID causes all "FOR BIT DATA" columns to be handled as text columns that need character set conversion and, therefore, any binary data in these columns can encounter conversion errors (ORA-28527).

### DRDA_DESCRIBE_TABLE

Default value: `TRUE`

Range of values: {`TRUE`|`FALSE`}

Syntax: `DRDA_DESCRIBE_TABLE={``TRUE|FALSE``}`

`DRDA_DESCRIBE_TABLE` directs the gateway to use the DRDA operation `Table Describe` to return the description of tables. This is an optimization that reduces the amount of time and resources that are used to look up the definition of a table.

Note: This feature is not compatible with DB2 Aliases or Synonyms. If you use DB2 aliases, then be sure to disable this option.

### DRDA_DISABLE_CALL

Default value: `TRUE`

Range of values: {`TRUE`|`FALSE`}

Syntax: `DRDA_DISABLE_CALL={``TRUE|FALSE``}`

`DRDA_DISABLE_CALL` controls stored procedure usage, and is also used to control how the package is bound on the target database. This parameter should be set to FALSE only for supported target DRDA servers and should be set to TRUE otherwise. See Chapter2, "DB2 Considerations" for supported target servers.

Note: Any change to this parameter requires you to rebind.

### DRDA_FLUSH_CACHE

Default value: `SESSION`

Range of values: {`SESSION`|`COMMIT`}

Syntax: `DRDA_FLUSH_CACHE={``SESSION|COMMIT``}`

`DRDA_FLUSH_CACHE` specifies when the cursor cache is to be flushed. With `DRDA_FLUSH_CACHE`=`COMMIT`, the cursor cache is flushed whenever the transaction is committed. With `DRDA_FLUSH_CACHE`=`SESSION`, the cache is not flushed until the session terminates.

### DRDA_GRAPHIC_CHAR_SIZE

Default value: 4

Range of values: 1 through 4

Syntax: `DRDA_GRAPHIC_CHAR_SIZE`=`num`

`DRDA_GRAPHIC_CHAR_SIZE` is used to define the character conversion size to be used for `GRAPHIC` data types. It is a tuning parameter which affects the maximum size of a `GRAPHIC` data type when the column is described.

### DRDA_GRAPHIC_PAD_SIZE

Default value: 0

Range of values: 0 through 127

Syntax: `DRDA_GRAPHIC_PAD_SIZE=num`

`DRDA_GRAPHIC_PAD_SIZE` is used to pad the size of a Graphic column as described by the DRDA Server. This is sometimes necessary depending upon the character set of the DRDA database and Oracle Database. If the Oracle database is based on `EBCDIC` and the DRDA database is based on ASCII, then a pad size of 2 may be needed.

### DRDA_GRAPHIC_LIT_CHECK

Default value: `FALSE`

Range of values: {`TRUE`|`FALSE`}

Syntax: `DRDA_GRAPHIC_LIT_CHECK={``TRUE|FALSE``}`

`DRDA_GRAPHIC_LIT_CHECK` directs the gateway to evaluate string literals within `INSERT` SQL statements in order to determine if they need to be converted to double-byte format for insertion into a Graphic column at the DRDA Server database. This is done by querying the column attributes of the table in the SQL statement to determine if a string literal is being applied to a column with a Graphic data type. If the table column is Graphic, and if this parameter is `TRUE`, then the gateway will rewrite the SQL statement with the literal converted to double-byte format. Existing double-byte characters in the string will be preserved, and all single-byte characters will be converted to double-byte characters.

### DRDA_GRAPHIC_TO_MBCS

Default value: `FALSE`

Range of values: {`TRUE`|`FALSE`}

Syntax: `DRDA_GRAPHIC_TO_MBCS={``TRUE|FALSE``}`

`DRDA_GRAPHIC_TO_MBCS` directs the gateway to convert graphic data that has been fetched from the DRDA Server into Oracle multi-byte data, translating double-byte characters into single-byte characters where possible.

### DRDA_ISOLATION_LEVEL

Default value: `CHG` for DB2/400, CS for DB2/OS390, DB2/UDB, DB2/VM

Range of values: {`CHG`|`CS`|`RR|ALL|NC`}

Syntax: `DRDA_ISOLATION_LEVEL={``CHG|CS|RR|ALL|NC``}`

`DRDA_ISOLATION_LEVEL` specifies the isolation level that is defined to the package when it is created. All SQL statements that are sent to the remote DRDA database are executed with this isolation level. Isolation level seriously affects performance of applications. Use caution when specifying an isolation level other than the default. For information on isolation levels, refer to your IBM database manuals.

The following table lists the isolation levels and their descriptions. The levels are specified in ascending order of control, with `CHG` having the least reliable cursor stability and `RR` having the most. Note that higher stability uses more resources on the server and can lock those resources for extended periods.

Table C-1 Isolation Levels and Their Descriptions

Level | Description
--- | ---
`CHG` | Change (default for DB2/400)
`CS` | Cursor Stability (default for DB2/UDB, DB2/OS390, and DB2/VM)
`RR` | Repeatable Read
`ALL` | ALL
`NC` | No Commit

Note: Any change to this parameter requires you to rebind.

### DRDA_LOCAL_NODE_NAME

Default value: `AIX_RS6K`

Range of values: any alphanumeric string 1 to 8 characters in length.

Syntax: `DRDA_LOCAL_NODE_NAME=``name`

`DRDA_LOCAL_NODE_NAME` specifies the name by which the gateway will be known to the DRDA Server. This name is used internally by the DRDA Server to identify the local node.

### DRDA_MBCS_TO_GRAPHIC

Default value: `FALSE`

Range of values: {`TRUE`|`FALSE`}

Syntax: `DRDA_MBCS_TO_GRAPHIC={``TRUE|FALSE``}`

`DRDA_MBCS_TO_GRAPHIC` directs the gateway to convert multi-byte data (that has been sent from Oracle to the DRDA database) into pure double-byte characters. This parameter is primarily intended to be used with bind variables in order to ensure that the data is properly formatted and will therefore be acceptable to the DRDA Server. It applies only to INSERT SQL statements that are using bind variables. When used in combination with the `DRDA_GRAPHIC_LIT_CHECK` parameter, this parameter can help ensure that data that is being inserted into a Graphic column is handled correctly by the target DRDA Server.

### DRDA_OPTIMIZE_QUERY

Default value: `TRUE`

Range of values: {`TRUE`|`FALSE`}

Syntax: `DRDA_OPTIMIZE_QUERY={``TRUE|FALSE``}`

`DRDA_OPTIMIZE_QUERY` enables or disables the distributed query optimizer (DQO) capability. Refer to "Performing Distributed Queries" in Chapter 12, "Using the Oracle Transparent Gateway for DRDA". The DQO capability is useful for optimizing queries that access large amount of data, but it can add overhead to small queries.

This parameter is valid only if the DRDA Server is DB2/OS390 or DB2/VM. If the DRDA Server is DB2/400 or DB2/UDB, then you must set the value to `FALSE`.

### DRDA_PACKAGE_COLLID

Default value: `ORACLE`

Range of values: An alphanumeric string 1 to 18 characters in length

Syntax: `DRDA_PACKAGE_COLLID=``collection_id`

`DRDA_PACKAGE_COLLID` specifies the package collection ID. Note that in DB2/400, the collection ID is actually the name of an AS/400 library.

Note: Any change to this parameter requires you to rebind the package.

### DRDA_PACKAGE_CONSTOKEN

Default value: None, use the sample provided

Range of values: A 16-digit hexadecimal number

Syntax: `DRDA_PACKAGE_CONSTOKEN=``hexnum`

`DRDA_PACKAGE_CONSTOKEN` specifies the package consistency token. This is a 16-digit hexadecimal representation of an 8-byte token. Oracle Corporation recommends that you do not change the consistency token. The consistency token used at runtime must match the one used when the package is bound. The value depends on the DRDA Server being used.

Note: Any change to this parameter requires you to rebind the package.

### DRDA_PACKAGE_NAME

Default value: G2DRSQL

Range of values: An alphanumeric string 1 to 18 characters in length

Syntax: `DRDA_PACKAGE_NAME=``name`

`DRDA_PACKAGE_NAME` specifies the package name. Note that the package is stored in the DRDA Server under this name as a SQL resource. Refer to the DRDA Server documentation for length limitations package names. Many typical implementations restrict the length to 8 characters.

Note: Any change to this parameter requires that you rebind the package.

### DRDA_PACKAGE_OWNER

Default value: None

Range of values: Any valid user ID

Syntax: `DRDA_PACKAGE_OWNER=``userid`

`DRDA_PACKAGE_OWNER` specifies the database user ID that owns the package. This enables the owner to be a user other than the connected user ID when the package is created. The package owner must be the same user as the owner of the `ORACLE2PC` table. This is not valid for DB2/VM.

Note: Any change to this parameter requires you to rebind the package.

### DRDA_PACKAGE_SECTIONS

Default value: 100

Range of values: Any integer between 1 and 65535

Syntax: `DRDA_PACKAGE_SECTIONS=``num`

`DRDA_PACKAGE_SECTIONS` specifies the number of cursors declared at the remote database when the package is bound. This is the maximum number of open cursors permitted at any one time. Change this parameter only if an application needs more than 100 open concurrent cursors.

Note: Any change to this parameter requires you to rebind the package.

### DRDA_READ_ONLY

Default value: FALSE

Range of values: {TRUE|FALSE}

Syntax: `DRDA_READ_ONLY={``TRUE|FALSE``}`

DRDA_READ_ONLY specifies whether the gateway runs in a read-only transaction mode. In this mode, SQL statements that modify data are not permitted.

### DRDA_RECOVERY_PASSWORD

Default value: none

Range of values: any valid password

Syntax: `DRDA_RECOVERY_PASSWORD=``passwd`

DRDA_RECOVERY_PASSWORD is used with the DRDA_RECOVERY_USERID. The recovery user connects to the IBM database if a distributed transaction is in doubt. For more information, refer to "Two-Phase Commit Processing". Also, refer to Chapter 14 for information about security and encrypting passwords.

### DRDA_RECOVERY_USERID

Default value: `ORARECOV`

Range of values: Any valid user ID

Syntax: `DRDA_RECOVERY_USERID=``userid`

`DRDA_RECOVERY_USERID` specifies the user ID that is used by the gateway if a distributed transaction becomes in doubt. This user ID must have execute privileges on the package and must be defined to the IBM database.

If a distributed transaction becomes in doubt, then the Oracle integrating server determines the status of the transaction by connecting to the IBM database, using the `DRDA_RECOVERY_USERID`. If this parameter is missing,then the gateway attempts to connect to a user ID of `ORARECOV`. For more information, refer to "Two-Phase Commit Processing".

### DRDA_REMOTE_DB_NAME

Default value: DB2V2R3

Range of values: An alphanumeric string 1 to 18 characters in length

Syntax: `DRDA_REMOTE_DB_NAME=``name`

`DRDA_REMOTE_DB_NAME` specifies the DRDA Server location name. This is an identifying name that is assigned to the server for DRDA purposes. A technique for determining this name by using a SQL `SELECT` statement is discussed in each of the server-specific installation sections in Chapter 5, "Configuring the DRDA Server".

### DRDA_SECURITY_TYPE

Default value: PROGRAM

Range of values: {`PROGRAM`|`SAME`}

Syntax: `DRDA_SECURITY_TYPE={``PROGRAM|SAME``}`

`DRDA_SECURITY_TYPE` specifies the type of security used for SNA communications. For more information about types of security and about setting `DRDA_SECURITY_TYPE`, refer to Chapter 14, "Security Considerations". Also refer to Chapter 15 for information on security and encrypting passwords.

### FDS_CLASS

Default value: `TG4DRDA_DB2MVS`

Range of values: Refer to the list below for valid values

Syntax: `FDS_CLASS=``TG4DRDA_DB2MVS`

`FDS_CLASS` specifies the capability classification used by Oracle Database and the gateway. These values may change from release to release, depending on whether the gateway capabilities change.

The valid default values for FDS_CLASS are as follows:

For a DB2/OS390 database: `TG4DRDA_DB2MVS`

For a DB2/VM database: `TG4DRDA_DB2VM`

For a DB2/400 database: `TG4DRDA_DB2400`

For a DB2/UDB database: `TG4DR` `DA_DB2UDB`

### FDS_CLASS_VERSION

Default value: 10.1.0.2.0

Range of values: 10.1.0.2.0

Syntax: `FDS_CLASS_VERSION=1`

`FDS_CLASS_VERSION` specifies the version of the `FDS_CLASS` capabilities. Do not specify this parameter unless directed to do so by Oracle Support Services.

### FDS_INSTANCE

Default value: DRD1

Range of values: the name of the gateway SID

Syntax: `FDS_INSTANCE=``drdahoa1`

`FDS_INSTANCE` specifies a subset of the `FDS_CLASS` capabilities that may be modified by the user, based on initialization file parameters. If you do not specify this parameter, then its value will be the Oracle SID that is defined in the `TNS Listener` entry.

### HS_FDS_FETCH_ROWS

Default value: 20

Range of values: Any integer between 1 and 1000

Syntax: `HS_FDS_FETCH_ROWS=``num`

`HS_FDS_FETCH_ROWS` specifies the fetch array size. This is the number of rows to be fetched from the DRDA Server and to return to Oracle Database at one time. This parameter will be affected by the `HS_RPC_FETCH_SIZE` and `HS_RPC_FETCH_REBLOCKING` parameters. For further information on these parameters, refer to the section "Controlling the Array Fetch Between Agent and Non-Oracle Database" in the Oracle Database Heterogeneous Connectivity Administrator's Guide.

### HS_LANGUAGE

Default value: none

Range of values: any valid language specification

Syntax: `HS_LANGUAGE=language[``_territory.character_set` ]

`HS_LANGUAGE` specifies the language and the character set that the gateway will use to interact with the DRDA Server. Care must be taken in choosing the value of these parameters, especially when the gateway will be accessing GRAPHIC data. For additional details, refer to Appendix D and to the Oracle Database Heterogeneous Connectivity Administrator's Guide.

### HS_NLS_NCHAR

Default value: None

Range of values: Any valid character set specification

Syntax: `HS_NLS_NCHAR=``character_set`

Hs_nls_nchar specifies the character set that the gateway will use to interact with the DRDA Server when accessing Graphic data. Set this parameter to the same value as the character set component of the `HS_LANGUAGE` parameter. For additional details, refer to Appendix D and to the Oracle Database Heterogeneous Connectivity Administrator's Guide.

### LOG_DESTINATION

Default value: `$ORACLE_HOME/tg4drda/log/gateway sid_pid.log`

Range of values: Any valid file path

Syntax: `LOG_DESTINATION=``logpath`

`LOG_DESTINATION` specifies the destination for gateway logging and tracing. This parameter should specify a file. If the file already exists, it will be overwritten.

After any failure to open the logpath, a second attempt to open the default is made.

Usually, `LOG_DESTINATION` should specify a directory. If it is specified as a file, and if two or more users simultaneously use the same instance of the gateway, then they are writing to the same log. The integrity of this log is not guaranteed. If you do not specify this parameter, then the default is assumed.

### ORA_MAX_DATE

Default value: 4712-12-31

Range of values: Any valid date less than 4712-12-31

Syntax: `ORA_MAX_DATE=``yyyy-mm-dd`

`ORA_MAX_DATE` specifies the gateway maximum date value. If the fetched date value is larger than 4712-12-31, the gateway replaces the date value with the value defined by the `ORA_MAX_DATE` parameter. Any date between January 1, 4712 BC and December 31, 4712 AD is valid.

### ORA_NLS10

Default value: `$ORACLE_HOME/nls/data`

Range of values: Any valid NLS directory path

Syntax: `SET ORA_NLS10=``nlspath`

`ORA_NLS10` specifies the directory to which the gateway loads its character sets and other language data. Normally this parameter does not need to be set. Some configurations, however, may require that it be set.

### ORACLE_DRDA_TCTL

Default value: None

Range of values: Any valid file path

Syntax: `ORACLE_DRDA_TCTL=``tracecontrolpath`

`ORACLE_DRDA_TCTL` specifies the path to the DRDA internal trace control file. This file contains module tracing commands. A sample file is stored in `$ORACLE_HOME/tg4drda/admin/debug.tctl.` This parameter is used for diagnostic purposes.

### ORACLE_DRDA_TRACE

Default value: value specified for `LOG_DESTINATION`

Range of values: any valid file path

Syntax: `ORACLE_DRDA_TRACE=``logpath`

`ORACLE_DRDA_TRACE` is used to specify a different log path for DRDA internal tracing. This tracing is separate from the rest of the gateway tracing, as specified by the `LOG_DESTINATION` parameter. By default, this parameter will append the DRDA internal trace to the gateway trace. This parameter is used for diagnostic purposes.

### TRACE_LEVEL

Default Value: 0

Range of values: 0-255

Syntax: `TRACE_LEVEL=``number`

`TRACE_LEVEL` specifies a code tracing level. This value determines the level of detail which is logged to the gateway logfile during execution. This parameter is primarily used for diagnostics.